P á g i n a 1 | 41
Proyecto GIFTCARD
Contenido
153802 HU_EP_GEO_Gifrcard_Fase_1_CONSULTA DE SALDO DE BONOS ...................... 5
Contexto ................................................................................................................................ 5
Configuración ........................................................................................................................ 5
153805 HU_EP_GEO_Gifcard_Fase_1_USO PARCIAL DE BONOS EN VENTA .................... 5
Contexto ................................................................................................................................ 5
Configuración ........................................................................................................................ 5
153808 HU_EP_GEO_Gifrcard_Fase_1_Consulta Transaccional de Bonos ...................... 6
Contexto ................................................................................................................................ 6
156990 HU_EP_GEO_Gifcard_Fase_1_Anulacion redención parcial de Bonos ................ 6
Contexto ................................................................................................................................ 6
156995 HU_EP_GEO_Gifrcard_Fase_1_REEMPLAZO DE BONOS ..................................... 7
Contexto ................................................................................................................................ 7
156999 HU_EP_GEO_Gifrcard_Fase_1_REEMISION DE BONOS ....................................... 7
Contexto ................................................................................................................................ 7
157002 HU_EP_GEO_Gifrcard_Fase_1_CAMBIO DE BONO POR EFECTIVO ..................... 8
Contexto ................................................................................................................................ 8
156987 HU_EP_GEO_Gifrcard_Fase_1_Consulta Transaccional de Bonos - Parte 2
(Factura, Acta, Dev) ................................................................................................................... 8
Contexto ................................................................................................................................ 8
Configuración ........................................................................................................................ 8
Servicios ................................................................................................................................. 8
160546 HU_EP_GEO_Gifrcard_Fase_1_Hybris - Place Market_Consulta de Bonos ......... 9
Contexto ................................................................................................................................ 9
160557 HU_EP_GEO_Gifrcard_Fase_1_Hybris - Place Market_Redención de Bonos ...... 9
Contexto ................................................................................................................................ 9
160575 HU_EP_GEO_Gifrcard_Fase_1_Hybris - Place Market_Anulación Redención ... 10
Contexto .............................................................................................................................. 10
166323 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Geoconciliación Transacciones –
Controles ................................................................................................................................. 11
Contexto .............................................................................................................................. 11
Configuración ...................................................................................................................... 11
P á g i n a 2 | 41
166315 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Geoconciliación Transacciones-Menu
de bonos .................................................................................................................................. 11
Contexto .............................................................................................................................. 11
166321 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Migracion de Bono Report ................ 12
Contexto .............................................................................................................................. 12
Configuración en la base de datos ...................................................................................... 12
166316 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Geoconciliación Transacciones -
Informe de Bonos .................................................................................................................... 13
Contexto .............................................................................................................................. 13
Configuración ...................................................................................................................... 13
173026 HU_EP_GEO_Reporte de Bono-Filtro Por Tipo de Bono .................................... 14
Contexto .............................................................................................................................. 14
169577 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Aprovechamiento de Bonos con Saldo
Parcial ...................................................................................................................................... 14
Contexto .............................................................................................................................. 14
Configuraciones ................................................................................................................... 14
170740 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Geoconciliación Exportación ERP
Bonos ....................................................................................................................................... 14
Contexto .............................................................................................................................. 14
173030 HU_EP_GEO_Reporte de Bono-Separación de Redenciones............................. 15
Contexto .............................................................................................................................. 15
183383 HU_EP_GEO_Creación de Documento Digital para Redención Parcial de Bonos
15
Contexto .............................................................................................................................. 15
183427 HU_EP_GEO_Saldo en la factura para redención parcial de bonos ................... 15
Contexto .............................................................................................................................. 15
186748 HU-BONOS-DEV-PARCIAL-001 ............................................................................ 16
Contexto .............................................................................................................................. 16
186778 HU-BONOS-REENVIO-001 ................................................................................... 16
Contexto .............................................................................................................................. 16
199765 HU_EP_GEO_GiftCard_Fase_2_Carga de Inventario ......................................... 16
Contexto .............................................................................................................................. 16
Configuraciones ................................................................................................................... 16
199772 HU_EP_GEO_GiftCard_Fase_2_Venta GiftCard P.Natural ................................. 17
Contexto .............................................................................................................................. 17
Configuración ...................................................................................................................... 18
202506 HU_EP_GEO_GiftCard_Fase_2_Anulación GiftCard .......................................... 19
P á g i n a 3 | 41
Contexto .............................................................................................................................. 19
202510 HU_EP_GEO_GiftCard_Fase_2_Devolución GiftCard ........................................ 19
Contexto .............................................................................................................................. 19
200941 HU_Mostrar Tabla Modificada (En caso de aplicar) / Opción Bono No Seguro . 19
Contexto .............................................................................................................................. 19
201999 HU_EP_INT_9572_Agregar Campo Mail Servicio Consulta Bono ...................... 20
Contexto .............................................................................................................................. 20
209569 HU_EP_GEO_GiftCard_Fase_2_Consulta GiftCard ............................................ 20
Contexto .............................................................................................................................. 20
207535 HU_EP_GEO_GiftCard_Fase_2_Redención.COM ............................................... 20
Contexto .............................................................................................................................. 20
206696 HU_EP_GEO_GiftCard_Fase_2_Redención GiftCard ......................................... 20
Contexto .............................................................................................................................. 20
Configuración ...................................................................................................................... 21
213788 HU_EP_GEO_Mensaje de Excepción en Cajas por Estado de Giftcard .............. 22
Contexto .............................................................................................................................. 22
213774 HU_EP_GEO_Adición Número de Giftcard Consulta de Movimientos de Giftcard
22
Contexto .............................................................................................................................. 22
212954 HU_EP_GEO_Ampliación de endpoints de consulta de bonos con campo y
búsqueda por número de Giftcard .......................................................................................... 23
Contexto .............................................................................................................................. 23
212963 HU_EP_GEO_Adición de columna Número de Giftcard en informe de Bonos –
GeoConciliación ....................................................................................................................... 23
Contexto .............................................................................................................................. 23
217498 - HU_EP_GEO_GiftCard_Fase_2_Reporte Ventas GiftCard ............................... 23
Contexto .............................................................................................................................. 23
Detalle del servicio .............................................................................................................. 23
217349 - HU_EP_GEO_GiftCard_Fase_2_Actualizaciones Forma GiftCard .................... 24
Contexto .............................................................................................................................. 24
Configuración ...................................................................................................................... 24
221805 - HU_EP_GEO_GiftCard_Fase2_Activación Masiva GiftCard ............................. 25
Contexto .............................................................................................................................. 25
Carga del archivo ................................................................................................................. 25
240811 - HU_EP_GEO_Conciliacion_Bonos_JSON .......................................................... 27
Contexto .............................................................................................................................. 27
P á g i n a 4 | 41
Detalle del servicio .............................................................................................................. 27
Diagrama de arquitectura de los componentes involucrados ................................................ 33
Servicios web disponibles ....................................................................................................... 38
P á g i n a 5 | 41
153802 HU_EP_GEO_Gifrcard_Fase_1_CONSULTA DE SALDO DE BONOS
Contexto
Con esta HU se crea una funcionalidad que permite consultar el saldo de los bonos, a la misma se puede acceder
con el menú de consulta rápida por medio de la barra espaciadora para el cual el cajero no necesita estar logueado,
adicionalmente se puede realizar la consulta desde ingreso de cliente, para esto se puede ingresar los datos del
bono o escanearlos.
Seleccionando la opción 2 e ingresando el numero de bono, se visualiza la información del mismo
Configuración
Archivo: pos-production.properties
Ubicación: geopos2-alkosto/configuration/pos/
Descripción: permite habilitar o deshabilitar la consulta de saldo de bonos
Propiedad: bono.query.optionMenu
Valor: true o false, donde el valor true indica que permite realizar la consulta.
153805 HU_EP_GEO_Gifcard_Fase_1_USO PARCIAL DE BONOS EN VENTA
Contexto
En esta HU se permite habilitar la redención parcial para los distintos tipos de bonos, se cuenta con una propiedad
que permite habilitar o deshabilitar la redención parcial de cada tipo de bono, al seleccionar el medio de pago bono,
en el momento de la redención el cajero puede seleccionar la tecla T para redención total, P para redención parcial.
En el caso de redención parcial se registrará un nuevo movimiento de uso en las transacciones del bono en la base
de bono-service, dicho estado es USED
Configuración
Archivo: pos-production.properties
Ubicación: geopos2-alkosto/configuration/pos/
Descripción: permite habilitar o deshabilitar la redencion parcial de cada tipo de bono.
Propiedad: enabled.partial.use.bonos={"refundBonoEnabled"\:true, "giftBonoEnabled"\:true,
"incentiveBonoEnabled"\:true, "winnerBonoEnabled"\:false}
Valor: true o false, donde el valor true indica que permite redención parcial.
Al ingresar el bono como medio de pago, se visualizará la información del mismo; en caso de tener habilitada la
redención parcial para ese tipo de bonos, se habilitará la opción de uso parcial mediante la tecla P o uso total con la
tecla T
Suponiendo que se usa el bono de forma parcial, por un monto de 3000, en la base de bonos en mongo, se registra
el movimiento de uso dentro de los stateSource
P á g i n a 6 | 41
db.getCollection("bonos").find({_id:"13B1070232OL"})
Al realizar el uso parcial se observa la actualización del campo "currentBalance" : 17000.0, el cual registra el saldo
actual del bono
En la impresión de la factura, se adiciona una sección con el saldo del bono
153808 HU_EP_GEO_Gifrcard_Fase_1_Consulta Transaccional de Bonos
Contexto
Con esta HU se crean servicios que permiten realizar la consulta transaccional de los bonos por distintos datos de
entrada, estos servicios serán consumidos por el módulo de consultas, pasando por intermedio de Mulesoft, los
distintos servicios se encuentran disponibles en bono-service:
/bonos/findBy/number/{bono_number}
/bonos/findBy/invoice/{invoice_number}
/bonos/findBy/acta/{acta_number}
/bonos/findBy/client/{client_number}
Revisar documentación detallada de los servicios en el documento adjunto al azure
156990 HU_EP_GEO_Gifcard_Fase_1_Anulacion redención parcial de
Bonos
Contexto
En esta HU se permite realizar la anulación de la redención parcial de bonos, se registra un nuevo estado en las
transacciones del bono, VOIDED_USE y se reestablece el saldo del bono al balance actual del mismo. Este
movimiento se registra cuando se hace la anulación de una venta que se pago parcialmente con un bono.
En la base de bonos en mongo, registra el movimiento de uso dentro de los stateSource
db.getCollection("bonos").find({_id:"13B1070232OL"})
P á g i n a 7 | 41
156995 HU_EP_GEO_Gifrcard_Fase_1_REEMPLAZO DE BONOS
Contexto
En esta HU se permite realizar el reemplazo de bonos que han sido utilizados parcialmente, el nuevo bono se emite
por el saldo actual del bono y se mantiene la relación entre el bono original y el nuevo bono.
Se emite el acta del nuevo bono
En la base de bonos, el bono original queda en state “VOIDED”, saldo 0 y registra dentro de los stateSource el
movimiento de anulación, referenciando al nuevo bono en el campo “replacementBonoId”
Se crea el nuevo bono por el currentBalance que tenía el bono reemplazado, donde también referencia al bono
original, en el campo replaceBonoId
156999 HU_EP_GEO_Gifrcard_Fase_1_REEMISION DE BONOS
Contexto
En esta HU se permite realizar la reemisión de bonos que han sido utilizados parcialmente, el nuevo bono se emite
por el saldo actual del bono y se mantiene la relación entre el bono original y el nuevo bono.
P á g i n a 8 | 41
Esta HU es similar que la HU anterior, la diferencia entre el reemplazo y la reemisión, es que para la remisión el
bono debe estar vencido.
157002 HU_EP_GEO_Gifrcard_Fase_1_CAMBIO DE BONO POR EFECTIVO
Contexto
En esta HU se permite realizar el cambio de bono por efectivo del saldo actual del bono, aunque el mismo haya sido
usado parcialmente, esto aplica para bono regalo y bonos cambio.
En la base de bonos se registra dentro de los stateSource del bono, el movimiento de cambio por efectivo
“CASH_EXCHANGE” y el bono queda en estado USED
156987 HU_EP_GEO_Gifrcard_Fase_1_Consulta Transaccional de Bonos -
Parte 2 (Factura, Acta, Dev)
Contexto
Con esta HU se complementan los servicios de consulta transaccional para poder consultar por numero de factura.
Adicionalmente se agrega una propiedad en bono-service que permite configurar cuantos registros se retornan en
el servicio.
Configuración
Archivo: aplication.yml
Ubicación: conf/application.yml
Descripción: permite configurar cuantos registros se retornan en los servicios
Propiedad: bono.service.query.response.limit
Valor: 10
En el documento bono del aplicativo bono-service de mongoDB, se agrega en la estructura del "stateSource" los
siguientes atributos:
Atributo: stateSource.invoiceNumber
Descripción: Indica el número de factura de la transacción.
Atributo: stateSource.extendedInvoiceNumber
Descripción: Indica el número extendido de factura de la transacción.
Atributo: stateSource.actaNumber
Descripción: Indica el número de acta de una transacción que genere bono regalo.
Servicios
Consulta Transaccional por documento de Factura
Método: GET
Endpoint: /bonos/findBy/invoice/{invoice_number}?&last_id={last_bono_number}&limit={number_entries}
Consulta Transaccional por documento de Acta
Método: GET
Endpoint: /bonos/findBy/acta/{acta_number}?&last_id={last_bono_number}&limit={number_entries}
P á g i n a 9 | 41
Consulta Transaccional por documento de Cliente
Método: GET
Endpoint: /bonos/findBy/client/{client_number}?&last_id={last_bono_number}&limit={number_entries}
160546 HU_EP_GEO_Gifrcard_Fase_1_Hybris - Place Market_Consulta de
Bonos
Contexto
Con esta HU se realiza la migración del servicio de consulta de bonos que se utiliza desde hybris, desde SOAP a Rest,
para esto se crea un nuevo servicio REST en bono-service llamado "/findByPin" que es de tipo POST para ejecutar la
misma función que el servicio SOAP
Detalle de la documentación del servicio adjunta en el azure, se muestra un ejemplo del servicio
160557 HU_EP_GEO_Gifrcard_Fase_1_Hybris - Place Market_Redención
de Bonos
Contexto
Con esta HU se realiza la migración del servicio de redención y anulación de la redención de bonos que se utiliza
desde hybris, para esto se crea un nuevo servicio REST en bono-service llamado "/useOrReverse" que es de tipo
POST para ejecutar la misma función que el servicio SOAP.
Para este servicio se debe enviar en el campo “state” la funcionalidad a aplicar, en este caso el valor es “Redimir”.
Se agrega un ejemplo
P á g i n a 10 | 41
160575 HU_EP_GEO_Gifrcard_Fase_1_Hybris - Place Market_Anulación
Redención
Contexto
Con esta HU se realiza la migración del servicio de redención y anulación de la redención de bonos que se utiliza
desde hybris, para esto se crea un nuevo servicio REST en bono-service llamado "/useOrReverse" que es de tipo
POST para ejecutar la misma función que el servicio SOAP.
Para este servicio se debe enviar en el campo “state” la funcionalidad a aplicar, en este caso el valor es “Reversar”
Tanto para la redención como para la anulación de la redención se utiliza el mismo servicio con la diferencia del
parámetro de campo “state”.
Se agrega un ejemplo
P á g i n a 11 | 41
166323 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Geoconciliación
Transacciones – Controles
Contexto
Con esta HU se busca generar una configuración en el módulo de GEOConciliacion para los distintos tipos de bonos
donde se permita configurar para cuales se quiere permitir la funcionalidad de redención parcial
Configuración
Archivo: tol-production.properties
Ubicación: conf/tol-production.properties
Descripción: permite habilitar o deshabilitar la redencion parcial de cada tipo de bono.
Propiedad: enabled.partial.use.bonos={"refundBonoEnabled"\:true, "giftBonoEnabled"\:true,
"incentiveBonoEnabled"\:true, "winnerBonoEnabled"\:false}
Valor: true o false, donde el valor true indica que permite redención parcial.
166315 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Geoconciliación
Transacciones-Menu de bonos
Contexto
Con esta HU se busca permitir la redención parcial de los bonos desde el módulo de GEOConciliacion ya sea por el
menú de redención o por asientos, teniendo en cuenta si se tiene la funcionalidad habilita por la propiedad
“enabled.partial.use.bonos”, la cual definirá para que tipos de bonos se permite la redención parcial
Redención por menú de redención
En la base de bonos, se registra el uso parcial del mismo
P á g i n a 12 | 41
Redención por asiento
166321 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Migracion de Bono
Report
Contexto
Con esta HU se busca alimentar la base de datos de bono-service con los campos que actualmente se almacenan en
la bono-report, para que los reportes se puedan obtener directamente desde bono-service y no de la bono-report.
Se nutre la base de bonos con los campos que se tienen actualmente en bono-report
Configuración en la base de datos
MongoDB
BONO_REPORT
_id
bonoNumber
balance
amount
clientId
clientId
clientDoc
clientDocumentType
expirationDate
vtoDate
clientName
clientName
conceptCode + conceptDescription
concept
subConceptCode + subConceptDescription
subConcept
cashierId
cashier
replacedBonoId
bonoNumberToReplace
P á g i n a 13 | 41
beneficiaryMail
beneficiaryMail
securityCode
securityCode
observation
observation
concept
saleBonoConcept
retentionAmount
retentionAmount
activationDate
emition_date
extendedInvoiceNumber
emition_document
acta
actaNumber
beneficiaryName
beneficiaryName
beneficiaryId
beneficiaryDocument
businessUnit
emissionBussinesUnit
digitalSending
digitalSending
channel
channel
pin
pin_internet
166316 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Geoconciliación
Transacciones - Informe de Bonos
Contexto
Con esta HU se modificó la lógica en el aplicativo GEOConciliacion para obtener la información del reporte Informe
de Bono dado la configuración de la fecha (formato YYYY-MM-DD):
Si la fecha configurada es anterior a la fecha actual, el sistema obtiene la información de los bonos desde
la tabla bono_report de la base de datos del servidor central de GEOPos.
Si la fecha es igual o posterior a la fecha actual. el sistema obtiene la información desde el mongoDb del
servicio de bono-service
Configuración
Archivo: tol-production.properties
Ubicación: /srv/apache-tomcat-6.0.18-2/webapps/GeoConciliacion-web/WEB-INF/classes/tol-production.properties
Descripción: Permite configurar la fecha a partir de la cual se tomarán los datos para el informe de bonos la base
mongo.
Propiedad: date.use.bono.service.DB
Valor: fecha en el formato yyyy-MM-dd, ejemplo: date.use.bono.service.DB =2024-12-10
Dentro de reportes, se selecciona el Informe de bonos, el informe mantiene su estructura solo que los datos se
obtienen de una fuente datos diferente en función a la propiedad mencionada anteriormente
P á g i n a 14 | 41
173026 HU_EP_GEO_Reporte de Bono-Filtro Por Tipo de Bono
Contexto
Con esta HU se adiciona en GEOConciliacion, en la opción de generar el reporte de bonos un combo, que permita
seleccionar sobre qué tipo de bonos se desea obtener el reporte o una opción para consultar Todos los tipos de
bonos.
169577 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Aprovechamiento de
Bonos con Saldo Parcial
Contexto
Con esta HU se busca extender la funcionalidad de aprovechamiento de bonos que se exporta a PeopleSoft,
extendiéndola a los bonos que tienen saldo parcial, de manera que el aprovechamiento se realice contra el saldo
actual al momento del vencimiento.
En bono-balance-service se modifican los servicios "/aprovechamiento/export" y "/balance" para que vayan a
ejecutar las consultas correspondientes a bono-service y obtener los datos relevantes desde la base de datos de
mongo y no directamente desde bono-report.
Configuraciones
Archivo: application.properties
Ubicación: conf/application.properties en bono-balance-service
Descripción: Permite configurar el token de conexión contra bono-service
Propiedad: bono.service.authorization.token
Valor: l5Cqk2=n4mH)SOlJ'732lrC{>fKRY7jo@!psa|9p@M~i;6l5>?h0u__wvb<F5rG@
Descripción: Permite configurar la url de los servicios de bono-service
Propiedad: bono.service.url
Valor: http://localhost:7004/bonos/
170740 HU_EP_GEO_EP_GEO_Gifrcard_Fase_1_Geoconciliación
Exportación ERP Bonos
Contexto
Con esta HU se busca que la exportación del ERP se realice tomando como fuente de datos el bono-service y no
necesariamente la bono-report, tal como se mencionaba con el informe de bono, aplica la misma propiedad de la
fecha
Si la fecha configurada es anterior a la fecha actual, el sistema obtiene la información de los bonos desde
la tabla bono_report de la base de datos del servidor central de GEOPos.
Si la fecha es igual o posterior a la fecha actual. el sistema obtiene la información desde el mongoDb del
servicio de bono-service
En la opción de Reportes/Exportación ERP
P á g i n a 15 | 41
173030 HU_EP_GEO_Reporte de Bono-Separación de Redenciones
Contexto
Con esta HU se busca que el informe de bonos de GEOConciliacion pueda contar con los registros de las múltiples
redenciones parciales que se realizan sobre un bono, cada redención se representa en una línea separada del
informe.
Se observan múltiples redenciones de un mismo bono
183383 HU_EP_GEO_Creación de Documento Digital para Redención
Parcial de Bonos
Contexto
Con esta HU se permite dejar un registro digital del uso de bonos, cuando se realice una redención parcial de un
bono, se generará y almacenara automáticamente un documento digital con los datos de la transacción, el mismo
se almacena en un directorio configurado en la propiedad “pdf.report.path”, el cual tiene configurado la ruta:
/home/report_auditory/{LOCALID}/{POSID}/{FECHA}/USO_nombrearchivo.pdf
Donde el nombre del archivo es de la siguiente forma: USO_numeroBono_ticketnumber_localId_posId_fecha.pdf
Ejemplo: USO_13B1070232OL_526020_00B1_0007_15082025.pdf
183427 HU_EP_GEO_Saldo en la factura para redención parcial de bonos
Contexto
Con esta HU se adiciona en la impresión una sección para redención parcial de bonos, por lo tanto, cuando se
realice una redención parcial de un bono en una transacción de venta, la factura de venta muestra los datos del
saldo inicial, el valor redimido y el saldo final, para garantizar la trazabilidad del uso del bono, cumplir con los
lineamientos legales y brindar información clara al cliente sobre la transacción.
En la factura del ticket, dentro del detalle de los medios de pago se adiciona la siguiente sección:
P á g i n a 16 | 41
186748 HU-BONOS-DEV-PARCIAL-001
Contexto
Con esta HU se permite migrar la fuente de información para la devolución parcial de bonos y que dicha
información se pueda obtener desde la base mongo de bono-service.
Se modifica la consulta de los bonos habilitados para su devolución. Se implementa nuevo servicio en bono-service
para la consulta en lugar de bono-balance-service. El mismo devuelve los bonos habilitados para la devolución (en
estado activo y con currentBalance igual al balance). Adicionalmente, en lugar de eliminar el bono se genera el
estado de devolución, como se hacía ya en la devolución total de un ticket de venta de bonos.
186778 HU-BONOS-REENVIO-001
Contexto
Con esta HU se permite migrar la fuente de información para el reenvío de los bonos y que dicha información se
pueda obtener desde la base mongo de bono-service.
199765 HU_EP_GEO_GiftCard_Fase_2_Carga de Inventario
Contexto
Con esta HU se define crear un servicio para dar de alta las giftcard (realizar la carga de inventario), en dicho
servicio se recibirá la cantidad de tarjetas a crear y el aplicativo bono-service genera la información de las tarjetas
(numero de la giftcard, código scratch y pin de internet), retornando una lista con los datos de estas tarjetas para
que los mismos sean impresos en los respectivos plásticos de las tarjetas.
Tipo: POST
URL: /giftCard/generate
Parametro: “quantity” indica la cantidad de tarjetas a generar
Ejemplo: http://172.24.50.4:7004/giftCard/generate?quantity=2
Respuesta:
{
"giftCardsToPrint": [
{
"pinInternet": "TZT5JrWIgrOab06jIcIkjw==",
"scratchCode": "PrcTMsNZ35GOlFLDgGQkiw==",
"barCode": "sVsAN+v+2hh0OGlYvKhko7zb7koRo3GYSBtMZZGSUQ8="
},
{
"pinInternet": "vtPLd3A23fSmGmpK6pNTBA==",
"scratchCode": "/mDl/xyQ+fleLEgAMgkMlw==",
"barCode": "ZMBfeLGPP8ZUGfQn2vKzAlmf2R8z6JGNCSW7tHWYohU="
}
],
"message": "Se han generado correctamente las 2 GiftCards"
}
El largo del código de barras de la giftcard es configurable, el mismo se puede configurar en la siguiente propiedad:
Configuraciones
Aplicativo: bono-service
Archivo: application.yml
Ubicación: /conf/application.yml
Descripción: Permite configurar el tamaño del código de barras de la giftcard.
Propiedad: giftCard.size.barCode
Valor: 20 (por defecto)
Descripción: Permite configurar el tamaño de la cantidad de tarjetas a crear.
P á g i n a 17 | 41
Propiedad: giftCard.load.limit
Valor: 1000 (por defecto)
Descripción: Permite configurar el tamaño del código scratch.
Propiedad: giftCard.size.scratchCode
Valor: 6 (por defecto)
Descripción: Permite configurar el tamaño del pin de la giftcard.
Propiedad: giftCard.size.pinInternet
Valor: 12 (por defecto)
199772 HU_EP_GEO_GiftCard_Fase_2_Venta GiftCard P.Natural
Contexto
Con esta HU se busca permitir la venta de tarjetas giftcard, esto implica la venta a persona natural, para la cual se
ingresará al menú de bono, seleccionando la opción de venta de giftcard, escanenado o ingresando el numero de la
tarjeta y el monto correspondiente a la misma. En este caso la tarjeta que previamente estaba en estado
“PRINTING”, pasara a estado “ACTIVE” teniendo un bono asociado a la misma.
A nivel de impresión se generará un voucher de acta con los números de las giftcard vendidas en la transacción.
Para que las tarjetas tengan un concepto definido se debe agregar en la base el nuevo concepto
Script SQL: INSERT INTO concept_bono (send_mail, eliminate, concept_name) VALUES (false, false, 'Giftcard');
En ingreso de artículos, con la tecla “B” si la propiedad “sale.giftcard.enabled” está en true te permite seleccionar la
opción de seleccionar Venta de bono o Giftcard
Al ingresar a la venta de Giftcard, solicita el código de barras de la tarjeta, el cual se puede escanear o ingresar
manualmente y luego solicita el monto por el cual se va a vender dicha tarjeta.
Al final el ingreso de cada tarjeta, consulta al cajero si requiere ingresar más tarjetas, visualizando un resumen de
las ultimas X tarjetas ingresadas
Crea los bonos asociados a las tarjetas
Luego de ingresar los pagos, finalizando la venta, se genera el acta de las giftcard
P á g i n a 18 | 41
A su vez, en la base de bono-service se refleja el cambio en el estado de las giftcard dentro de la colección giftcard
pasando del estado “PRINTING” al estado “ACTIVE”, y le asocia el número de bono
{
"_id" : "ZsHcNf8Jc4HIxIL6ocvb/uNEdEaG+bXbSwIs0oRbKts=",
"barCode" : "ZsHcNf8Jc4HIxIL6ocvb/nq+nt6n92DuDqiB9UWSQ9U=",
"state" : "ACTIVE",
"bonoNumber" : "12B107546B0T",
"scratchCode" : "+GB74UigodJh9ar8C5CmfA==",
"pinInternet" : "LliigrDA5ft2dONghaFSYg==",
"createdDate" : ISODate("2025-08-18T19:26:04.466+0000"),
"updatedDate" : ISODate("2025-08-21T12:14:14.573+0000"),
"_class" : "uy.com.geocom.alkosto.bonoservice.domain.giftcard.GiftCard"
}
Al activar la tarjeta se le crea el bono, el cual referencia a la giftcard
En la base de geopos en los ticketitems de la venta de una giftcard, se agrega una nueva columna para guardar el
código de barra de la GiftCard asociada.
Configuración
Archivo: pos-production.properties
Ubicación: geopos2-alkosto/configuration/pos/
Descripción: permite habilitar o deshabilitar la venta de giftcards
Propiedad: sale.giftcard.enabled
Valor: true o false para habilitar o deshabilitar la venta de giftcard, donde el valor true le pregunta al cajero si quiere
vender bono o giftcard, en false va directo a la venta de bonos.
P á g i n a 19 | 41
202506 HU_EP_GEO_GiftCard_Fase_2_Anulación GiftCard
Contexto
Con esta HU en la transacción de anulación de un ticket de venta de una giftcard, hay un chequeo operativo por
parte del cajero de que la misma no esté dañada o raspada y se procede a anular el bono asociado a la giftcard y la
tarjeta queda en estado printing para que se pueda volver a vender.
202510 HU_EP_GEO_GiftCard_Fase_2_Devolución GiftCard
Contexto
Con esta HU se restringe la devolución de una giftcard, por lo cual si el cajero intenta realizar una devolución de una
venta de una giftcard se le mostrara un mensaje indicando que no es posible realizar la acción.
200941 HU_Mostrar Tabla Modificada (En caso de aplicar) / Opción Bono
No Seguro
Contexto
Con esta HU se busca homologar las tablas que muestran información de bonos, con el detalle de los bonos cambios
y la opción de bono no seguro acompasándose a otras iniciativas trabajadas por el equipo de celula 1.
Cuando se muestra la tabla de información de un bono cambio, al darle M para más detalles se visualizan datos de
la devolución que genero ese bono.
P á g i n a 20 | 41
201999 HU_EP_INT_9572_Agregar Campo Mail Servicio Consulta Bono
Contexto
Con esta HU se busca permitir adicionar el campo mail en el servicio de reenvio de bonos digitales
209569 HU_EP_GEO_GiftCard_Fase_2_Consulta GiftCard
Contexto
Con esta HU se busca adicionar a la consulta rápida (mediante la tecla “barra espaciadora”), que también se puedan
consultar datos de la giftcard, siempre y cuando la misma se haya activado previamente.
Al seleccionar la opción 2 e ingresar el código de barras de la giftcard, el cajero no visualizara todo el numero de la
tarjeta por temas de seguridad
Visualizando los datos de la tarjeta
207535 HU_EP_GEO_GiftCard_Fase_2_Redención.COM
Contexto
Con esta HU se busca reutilizar los servicios de consulta y redención de bonos en .com, así como la sección de pagos
en la IN-34, ya que si el cliente paga con una Giftcard en la sección de medios de pago se enviaran los mismo datos
que al realizar un pago con bonos, cuando se realiza la facturación en el aplicativo GEOPos se modifica el
procesamiento de la IN34 para validar en los pagos de Bono que los mismos pertenezcan a una Giftcard. Para esto
en el momento de la facturación automática, se consulta el bono y se valida si se el mismo tiene una giftcard
asociada, en dicho caso se registra el número de la misma en el pago asociado y se imprime la factura como una
redención de una Giftcard.
En la tabla payments, en el campo giftcard_barcode se registra el numero de la giftcard asociado al bono, en caso
de que el bono tenga una tarjeta asociada, de lo contrario queda vacío.
206696 HU_EP_GEO_GiftCard_Fase_2_Redención GiftCard
Contexto
Con esta HU se busca permitir la redención de las tarjetas giftcard en cajas físicas ya sea de forma parcial o total,
para esta redención se reutiliza el medio de pago existente para bono regalo. Se reutiliza todo lo definido
previamente para redención parcial de bonos en términos de impresión.
Se tienen propiedades para la configuración de los pagos, en caso de que el uso de giftcard y de bono regalo este
habilitado al mismo tiempo entonces al ingresar al medio de pago bono/tarjeta regalo se muestra una tabla
solicitando al usuario elegir si quiere pagar con un bono o con una giftcard
P á g i n a 21 | 41
Dado que se va a reutilizar el medio de pago existente para bono regalo, lo que se va a realizar es un renombre del
mismo con el siguiente script
Script SQL: UPDATE paymentmodes SET "name"='BONO/TARJETA REGALO' WHERE id='13';
Configuración
Archivo: pos-production.properties
Ubicación: geopos2-alkosto/configuration/pos/
Descripción: permite habilitar o deshabilitar el pago con bono regalo
Propiedad: sale.bono.enabled
Valor: true o false.
Descripción: permite habilitar o deshabilitar el uso de las tarjetas giftcards
Propiedad: sale.giftcard.enabled
Valor: true o false
En caso de mantener uno solo en true se redirige automáticamente al ingreso del medio de pago seleccionado
Al seleccionar el medio de pago 13, se procede con el pago, se visualizan ambas opciones (Bonos, Giftcard) y se
selecciona Giftcard, luego se debe ingresar el código de barras de la tarjeta y el código scratch
Con eso se visualiza la información de la tarjeta
Ingresando un pago parcial, se visualiza el resumen de los pagos ingresados
En el ticket impreso, en la sección de medios de pagos se observa el detalle de la tarjeta con su respectivo saldo
Así como en la base de datos de bonos, se observa el movimiento de redención del bono asociado a la giftcard en
los stateSource del bono
P á g i n a 22 | 41
213788 HU_EP_GEO_Mensaje de Excepción en Cajas por Estado de
Giftcard
Contexto
Con esta HU se busca homogeneizar los mensajes de errores para giftcard, y que los mismos se acoplen a los
definidos para bonos
Bono/Giftcard que no existe:
Bono: El bono ingresado no existe. Verifica el número e intenta nuevamente.
GiftCard: El número de tarjeta y/o pin de seguridad no coincide. Verifique e intente nuevamente.
Bono/Giftcard no activa:
Bono: Este bono aún no se encuentra vigente. Fecha de inicio de vigencia {fecha de activación}.
GiftCard: Esta GiftCard aún no se encuentra vigente. Fecha de inicio de vigencia {fecha de activación}.
Bono/Giftcard expirada:
Bono: Este bono ha vencido. Fecha de fin de vigencia {fecha de expiración}. Acercarse a servicio al cliente.
GiftCard: Esta GiftCard ha vencido. Fecha de fin de vigencia {fecha de expiración}. Acercarse a servicio al
cliente.
Bono/Giftcard sin saldo:
Bono: Este bono no tiene saldo disponible.
GiftCard: Esta GiftCard no tiene saldo disponible.
213774 HU_EP_GEO_Adición Número de Giftcard Consulta de
Movimientos de Giftcard
Contexto
Con esta HU se busca que en los servicios de consulta transaccional se pueda consultar por el numero de la giftcard
Consulta Transaccional por número de documento
Método: GET
Endpoint: /bonos/findBy/number/{document_number}
En la definición del Endpoint, la entrada {document_number} hace referencia al número de Bono o número de
Giftcard y es una entrada obligatoria para obtener la información transaccional asociado al tipo de documento.
Restricciones
Si {document_number} es menor a 12 dígitos, el servicio lanza un error 500.
Si {document_number} es igual a 12 dígitos, se realiza una búsqueda por número de bono.
Si {document_number} es mayor a 12 dígitos, se realiza una búsqueda por número de Giftcard (código de
barra).
Si se cumple el punto anterio y la cantidad de caracteres ingresados en el {document_number}, es mayor
al valor configurado en la propiedad "giftCard.size.barCode" que indica el largo del código de barra que se
imprime en la Giftcard, el servicio lanza un error genérico
P á g i n a 23 | 41
212954 HU_EP_GEO_Ampliación de endpoints de consulta de bonos con
campo y búsqueda por número de Giftcard
Contexto
Con esta HU se realizan los ajustes en los servicios de Consulta Transaccional por tipo de Documento (factura, acta o
cliente). En el listado de números de bonos que se obtiene, si el bono está asociado a una Giftcard entonces el
servicio retornara en el campo “giftcardNumber” el número de dicha tarjeta
{
"bonos": [
{
"giftcardNumber": "82824041021511931149",
"currentBalance": "20.000",
"initialBalance": "20.000",
"bonoNumber": "12B17251736H",
"activationDate": "2025-08-13",
"expirationDate": "2026-02-09",
"beneficiaryId": "1_11111"
}
]
}
212963 HU_EP_GEO_Adición de columna Número de Giftcard en informe
de Bonos – GeoConciliación
Contexto
Con esta HU se busca adicionar la columna “Nro. GiftCard” en el informe de bonos, la cual registrara el numero de la
tarjeta para los bonos que tengan asociada una giftcard
217498 - HU_EP_GEO_GiftCard_Fase_2_Reporte Ventas GiftCard
Contexto
Con esta HU se busca poder contar con un reporte que brinde información de las tarjetas. Pudiendo contar con
información genérica sobre el inventario, indicando cuantas tarjetas hay en cada estado y por otro lado contar con
información detallada, que permita obtener información por unidad de negocio.
Se crea un servicio en el aplicativo alkosto-report-service que permite obtener el detalle del inventario de las
giftcard, para las mismas se retorna la unidad de negocio en la cual se generó, fecha de la generación, estado actual
de la tarjeta (activa o usada) y el número de serial de la tarjeta
Adicionalmente se puede filtrar por unidad de negocio
La respuesta se retorna en un archivo csv
Detalle del servicio
Método HTTP: GET
Endpoint: http://{ipmicroservicios}:8046/report/giftcard/generateReport?businessUnit={UNIDAD_DE_NEGOCIO}
Tipo de respuesta: application/octet-stream (permite descargar en formato .csv)
P á g i n a 24 | 41
El parámetro unidad de negocio es opcional, en caso de no incluirlo mostrara el resultado para todas las unidades
de negocio
Ejemplo de respuesta
UNIDAD_NEGOCIO,FECHA,TIPO_TRANSACCIÓN,SERIAL
AKB68,2025-07-01 15:40:06,ACTIVA,0pJNbca+BC9DvG1evPy48goj0YPBI6e3UggMieG1GbA=
AKB68,2025-07-15 16:57:03,ACTIVA,uyHcOZHVfkwBgFPVzTb/Ui6F3Gi8wK+JV4Bd+tF/4yM=
AKB68,2025-07-24 16:57:49,USADA,RPtJjwjg394EF6n0mnYLVeOQES9ZBlJldwsGiVpYCQs=
Adicionalmente se cuenta con otro servicio que retorna la cantidad de tarjetas por unidad de negocio y estado de la
tarjeta
Método HTTP: GET
Endpoint:
http://{ipmicroservicios}:8046/report/giftcard/generateQuantityReport?businessUnit={UNIDAD_DE_NEGOCIO}
Tipo de respuesta: application/octet-stream (permite descargar en formato .csv)
Ejemplo de respuesta
UNIDAD_NEGOCIO,TIPO_TRANSACCIÓN,CANTIDAD
AKB68,USADAS,1
AKB68,ACTIVAS,4
AKB30,ACTIVAS,1
217349 - HU_EP_GEO_GiftCard_Fase_2_Actualizaciones Forma GiftCard
Contexto
Con esta HU se busca que el número de la giftcard no sea visible al cajero, para ello se realiza un enmascaramiento
del mismo y en todos los ingresos, mensajes, impresión, etc que se maneja el número de giftcard se visualizara
solamente los últimos X caracteres de dicha tarjeta, el resto se visualiza un * por cada dígito
La cantidad de caracteres a visualizar es configurable en una propiedad
Configuración
Archivo: pos-production.properties
Ubicación: geopos2-alkosto/configuration/pos/
Descripción: permite configurar que cantidad de los últimos X dígitos de la tarjeta serán visibles al cajero
Propiedad: giftcard.barcode.visible.character.size
Valor: 6
Ejemplos de cómo se visualiza el número de la tarjeta
P á g i n a 25 | 41
221805 - HU_EP_GEO_GiftCard_Fase2_Activación Masiva GiftCard
Contexto
Con esta HU se crea la funcionalidad de venta masiva de tarjetas giftcard. Para realizar el proceso, primero se
deberá generar un archivo en formato .csv con los datos correspondientes a la venta, dicho archivo debe ser
cargado al sistema mediante un web service, que dejará registradas las tarjetas en una colección llamada
“giftCardMassive” de la base bonos en mongodb, asociadas al cliente que realizará la compra de dichas tarjetas.
Para realizar la venta desde la caja, la misma se realizará desde la venta de giftcard, para cargar un archivo se
deberá ingresar con la “tecla A” lo cual permitirá visualizar los archivos disponibles para ese cliente
Carga del archivo
Primero se debe generar un archivo con los siguientes campos
documentId, localId, initDate, endDate, amount, concepto
giftcardId
giftcardId
Detalle de los campos (línea 1 - cabecera)
Campo
Descripción
Documento del Cliente
Número de identificación del cliente o entidad que realizó la compra
formato: tipoDocumento_numeroDocumento
Código de Local
Identificador del local donde se realizará la activación de las tarjetas
Fecha Inicio de la Disponibilidad del
archivo cargado
Fecha desde la cual se puede visualizar el archivo cargado (formato:
ddmmaaaa).
Fecha Fin Vigencia de la
disponibilidad del archivo cargado
Fecha de expiración de la visualización del archivo (formato: ddmmaaaa).
Motivo
Descripción corta del motivo de la carga
Detalle del contenido de las líneas
Campo
Descripción
Número de Giftcard
Número único de la tarjeta Giftcard a cargar (una por cada fila del archivo)
Ejemplo del archivo, en formato .csv
1_11111,B1,24082025,31122025,35000,Giftcard
82626077065521581220
82126078075521581221
82426079095521581229
Para cargar el archivo, se debe hacer uso del servicio disponible en el aplicativo bono-service
Método HTTP: POST
Endpoint: http://{ipmicroservicios}:7004/giftCard/massiveLoad
En el body del servicio cargar el archivo
P á g i n a 26 | 41
Al cargar el archivo, el mismo se registra en la base de bonos, en mongodb, en la colección “giftCardMassive”, el
archivo tiene como restricción que solo puede ser utilizado en el rango de fechas comprendidas entre initDate y el
endDate, aplica solo para el localId y cliente registrado, que será quien debe realizar la compra
En lo que respecta a los estados del archivo (campo “state”), cuando se carga el archivo queda en estado “LOAD”,
luego que se realiza la venta de las giftcard asociadas, el archivo cambia al estado “PROCESSED”.
Proceso de venta
Desde GEOPos para realizar la venta masiva de las tarjetas cargadas previamente en el archivo, se debe ingresar el
menú de venta de giftcard y allí presionar la tecla “A” y se visualizaran los archivos disponibles para ese
local/cliente. Donde se tiene la opción de seleccionar uno de ellos mediante la tecla Enter o con F9 se cargan a la
venta todos los archivos disponibles
Al cargar ambos archivos se visualizará un resumen de las tarjetas ingresadas
Al finalizar la venta se observa el acta con el detalle de las giftcard vendidas
P á g i n a 27 | 41
Así mismo, los archivos utilizados quedan en estado procesado
240811 - HU_EP_GEO_Conciliacion_Bonos_JSON
Contexto
Con esta HU se busca reutilizar la consulta del reporte de bonos de Goconciliación para
remplazar el antiguo reporte de Jasper que ejecuta la consulta contra la tabla bono_report. En
el servicio de bono-service se agregan los campos restantes para el reporte, pero estos no
serán visibles desde el reporte de Geoconcilación.
Detalle del servicio
Nombre del Servicio: bonoReportPageableGeneration
Método HTTP: POST
Endpoint: /bonos/
Tipo de respuesta: application/json
Parámetros de entrada
Parámetro
Tipo
Requerido
Descripción
type
Numérico
Sí
Indica el servicio a
ejecutar.
dateFrom
Texto
Sí
Fecha de inicio de
búsqueda en formato
“YYYY-MM-DD
HH:mm:ss”.
P á g i n a 28 | 41
dateEven
Texto
Sí
Fecha de fin de
búsqueda en formato
“YYYY-MM-DD
HH:mm:ss”.
catalog
Texto
No
Tipo de bono a filtrar
(“12” = Bono Regalo,
“13” = Bono Cambio,
“14” = Bono Ganador,
“15” = Bono Incentivo)
businessUnit
Lista
No
Unidad de negocio a
filtrar. (Ej: [“AKB68”,
“AKVEN”])
cursor
Texto
No
Luego de la primera
ejecución en caso de
que la respuesta tenga
más registros (hasNext =
true), se devuelve
también el campo
cursor con el valor a
utilizar para obtener los
próximos registros
(manteniendo el resto
del request tal cual la
primera ejecución).
limit
Numérico
Si
Indica la cantidad de
registros a devolver.
transactionId
Texto
Sí
Id único generado por el
cliente que invoca el
servicio.
Parámetros de salida
Parámetro
Tipo
Requerido
Descripción
type
String
Si
Indica el servicio
ejecutado.
statusCode
Numérico
Si
Código http de
respuesta del servicio.
hasNext
Boolean
Si
Indica si la consulta
tiene más registros
aparte del limit.
Cursor
String
No
Devuelve el cursor
para consultar los
siguientes registros
fuera del limit.
bonos
Lista de objetos
BonoReportItem
Sí
Estructura que detalla
los datos de los
registros del reporte.
BonoReportItem
Parámetro
Tipo
Requerido
Descripción
bonoType
String
Si
Indica el servicio
ejecutado.
P á g i n a 29 | 41
bonoNumber
String
Si
Número de bono
giftCardNumber
String
Si
Número de Giftcard
en caso de que el
bono esté asociado a
una.
bonoValue
Numérico
Sí
Valor referente al
movimiento de ese
registro (Ej: valor de
un uso o valor de una
activación)
currentBalance
Numérico
Sí
Saldo actual del bono.
clientIdType
Texto
Sí
Tipo de documento
del cliente
clientCode
Texto
Sí
Identificador del
cliente
clientName
Texto
Sí
Nombre del cliente.
actaNumber
Texto
Sí
Número de acta del
bono.
emissionDate
Texto
Sí
Fecha de emisión del
bono.
emissionInvoice
Texto
Sí
Número de factura en
la que se emitió el
bono.
redemptionDate
Texto
Sí
Fecha de redención
del movimiento.
redemptionBusinessU
nit
Texto
Sí
Unidad de negocio en
la que se redimió el
movimiento.
redemptionInvoice
Texto
Sí
Número de factura en
la que se redimió el
movimiento.
redemptionType
Texto
Sí
Tipo de redención
redemptionTypeDescr
iption
Texto
Sí
Descripción del tipo
de redención (“POS”,
“WEB”,
“GEOCONCILIACIÓN”)
portfolioRedemptionU
ser
Texto
Sí
Usuario redención
cartera
creditNoteNumber
Texto
Sí
Número Nota Crédito.
expirationDate
Texto
Sí
Fecha de expiración
del bono.
cleanIndicator
Texto
Sí
Indicador Limpieza
cleanDate
Texto
Sí
Fecha Limpieza
cleanConcept
Texto
Sí
Concepto Limpieza
cleanConceptDescripti
on
Texto
Sí
Descripción concepto
limpieza
cleanUser
Texto
Sí
Usuario limpieza
giftBono
Texto
Sí
Indica si el bono fue
emitido por el
P á g i n a 30 | 41
gerente. (“S” = Si, “N”
= No)
Concept
Texto
Sí
Concepto del bono
conceptDescription
Texto
Sí
Descripción del
concepto del bono
subConcept
Texto
Sí
Subconcepto del
bono.
subConceptDescriptio
n
Texto
Sí
Texto del
subconcepto del
bono.
User
Texto
Sí
Usuario
businessUnit
Texto
Sí
Unidad de negocio del
movimiento
returnDate
Texto
Sí
Fecha de devolución.
returnInvoice
Texto
Sí
Número de factura de
la devolución
replacementBono
Boolean
Sí
Indica si el bono fue
remplazado o
reemitido.
replacementBonoFile
Texto
Sí
Número del bono
remplazado
replacementFrom
Texto
Sí
Número de bono por
el que se remplazó
(para estados ACTIVE)
alkReplacementBono
Texto
Sí
Tipo del bono
remplazado
interfaceZone
Texto
Sí
Zona interfaz
bonoOrigin
Texto
Sí
Origen del bono.
redemptionUser
Texto
Sí
Usuario que redime el
bono.
annulmentUser
Texto
Sí
Usuario que anula el
bono.
annulmentReason
Texto
Sí
Razón de la anulación.
bonoStatus
Texto
Sí
Estado del
movimiento del
registro.
annulmentObservatio
n
Texto
Sí
Observación de la
anulación.
emissionBusinessUnit
Texto
Sí
Unidad de negocio
donde se emitió.
emissionObservation
Texto
Sí
Observación de la
emisión.
digitalSending
Boolean
Sí
Indica si el bono se
envió digitalmente.
causalBono
Texto
Sí
Causal del bono
Ejemplo:
http://{IP}:{PUERTO}/bonos/
P á g i n a 31 | 41
Request:
{
"dateFrom": "2025-05-27 00:00:00",
"dateEven": "2025-09-25 23:59:00",
"transactionId": "3164bcb7-8178-4189-ab9e-03921d6a65321",
"catalog": "",
"businessUnit": [
"AKB30", "AKB68"
],
"limit": 50,
"type": "bonoReportPageableGeneration"
}
Response:
{
"type": "bonoReportPageableGeneration",
"statusCode": 200,
"hasNext": true,
"cursor": "MjAyNS0wNy0wOFQxMzoyMzowMy45OTlaLDEyQjE0ODUwNTM3Uiwx",
"bonos": [
{
"bonoType": "12",
"bonoNumber": "12B148505300",
"giftCardNumber": null,
"bonoValue": -500.0,
"currentBalance": 0.0,
"clientIdType": "C",
"clientCode": "11111",
"clientName": "HILDA RUDAS",
"actaNumber": null,
"emissionDate": null,
"emissionInvoice": null,
"redemptionDate": "2025-08-26T11:05:36.366",
"redemptionBusinessUnit": null,
"redemptionInvoice": null,
"redemptionType": null,
"redemptionTypeDescription": null,
"portfolioRedemptionUser": "??",
"creditNoteNumber": "??",
"expirationDate": "2025-11-04T23:59:59",
"cleanIndicator": "0",
"cleanDate": null,
"cleanConcept": null,
"cleanConceptDescription": null,
"cleanUser": null,
"giftBono": null,
"concept": null,
P á g i n a 32 | 41
"conceptDescription": null,
"subConcept": null,
"subConceptDescription": null,
"user": null,
"businessUnit": null,
"returnDate": null,
"returnInvoice": null,
"replacementBono": false,
"replacementBonoFile": null,
"replacementFrom": null,
"alkReplacementBono": null,
"interfaceZone": "??",
"bonoOrigin": "Origen Geopos",
"redemptionUser": "web",
"annulmentUser": "",
"annulmentReason": null,
"bonoStatus": "Redencion",
"annulmentObservation": null,
"emissionBusinessUnit": null,
"emissionObservation": null,
"digitalSending": false,
"causalBono": "Fidelidad Alkosto-Ktronix Mail"
},
…
]
}
Ejemplo Curl:
curl --location 'http://{IP}:{PUERTO}:7004/bonos/' \
--header 'Authorization: {TOKEN} \
--header 'Content-Type: application/json' \
--data '{
"dateFrom": "2025-05-27 00:00:00",
"dateEven": "2025-09-25 23:59:00",
"transactionId": "3164bcb7-8178-4189-ab9e-03921d6a65321",
"catalog": "",
"businessUnit": [
"AKB30", "AKB68"
],
"limit": 50,
"type": "bonoReportPageableGeneration"
}'
P á g i n a 33 | 41
Diagrama de arquitectura de los componentes involucrados
Notas:
A efectos del cliente lo que visualiza es la Giftcard, sin embargo, dado que la Giftcard tiene
asociado un bono regalo, todos los movimientos se registran sobre el bono, siendo que tanto
el bono como la Giftcard tienen sus respectivos estados
La Giftcard no va a permitir reemplazo, reemisión, cambio por efectivo ni devolución, sin
embargo, si se permitirá la anulación siempre y cuando la tarjeta no esté raspada, para esto la
tarjeta física sigue estando en estado en impresión, pero el bono queda en estado anulado
P á g i n a 34 | 41
Estructura de la base de datos
Para todo el tema de bonos y Giftcard se utiliza la base de datos de bonos en MongoDB, a
continuación, se muestra un ejemplo de como quedan las estructuras en las distintas
colecciones
Base de datos: Bonos (MongoDB)
Colección “bonos”:
ACTIVE:
{
"_id": "12B171547399",
"balance": 400000,
"currentBalance": 400000,
"retentionAmount": 0,
"beneficiaryId": "1_111111",
"beneficiaryName": "MARIA PEREZ",
"clientId": "111111",
"clientName": "MARIA PEREZ",
"clientDoc": "CEDULA DE CIUDADANIA",
"clientDocType": "C",
"concept": "Giftcard",
"state": "ACTIVE",
"digitalSending": false,
"updated": {
"$date": "2025-09-18T12:41:54.089Z"
},
"createDate": {
"$date": "2025-09-18T12:41:54.084Z"
},
"activationDate": {
"$date": "2025-09-18T03:00:00.000Z"
},
"expirationDate": {
"$date": "2026-03-18T02:59:59.000Z"
},
"securityCode": "0hq89JCCDzm+xHphLoNLWg==",
"pin": "dBlOhQPliPBZfoegXgJyGw==",
"stateSource": [
{
"state": "ACTIVE",
"terminalId": "B171",
"ticketNumber": "826076",
"date": {
"$date": "2025-09-18T12:41:54.089Z"
},
"cashierId": "3",
"amount": 400000,
"invoiceNumber": "ctg750",
"extendedInvoiceNumber": "ctg00000000750",
"acta": "B1324",
"businessUnit": "AKBOL",
"giftBono": "N"
}
],
"giftCardId": "DBIL2ZqUk90hdtiZRbmHppYm+TNJzrZ6HolHsdeA/mU=",
"_class": "uy.com.geocom.alkosto.bonoservice.domain.Bono"
}
USED:
{
"_id": "12B171547398",
"balance": 500000,
"currentBalance": 0,
"retentionAmount": 0,
P á g i n a 35 | 41
"beneficiaryId": "1_111111",
"beneficiaryName": "MARIA PEREZ",
"clientId": "111111",
"clientName": "MARIA PEREZ",
"clientDoc": "CEDULA DE CIUDADANIA",
"clientDocType": "C",
"concept": "Giftcard",
"state": "USED",
"digitalSending": false,
"updated": {
"$date": "2025-09-18T18:52:13.804Z"
},
"createDate": {
"$date": "2025-09-18T12:41:54.026Z"
},
"activationDate": {
"$date": "2025-09-18T03:00:00.000Z"
},
"expirationDate": {
"$date": "2026-03-18T02:59:59.000Z"
},
"securityCode": "+GYs1pSdT50KnifAalNAcw==",
"pin": "6y/zgi6Mw5yZDEQ7UOJmwA==",
"stateSource": [
{
"state": "ACTIVE",
"terminalId": "B171",
"ticketNumber": "826076",
"date": {
"$date": "2025-09-18T12:41:54.040Z"
},
"cashierId": "3",
"amount": 500000,
"invoiceNumber": "ctg750",
"extendedInvoiceNumber": "ctg00000000750",
"acta": "B1324",
"businessUnit": "AKBOL",
"giftBono": "N"
},
{
"state": "USED",
"terminalId": "B171",
"ticketNumber": "826077",
"date": {
"$date": "2025-09-18T14:05:55.978Z"
},
"cashierId": "3",
"amount": -31950,
"beforeBalance": 500000,
"invoiceNumber": "ctg751",
"extendedInvoiceNumber": "ctg00000000751",
"transactionId": "db87e1f4-1133-40cf-8747-6af2fa876545",
"observation": "POS",
"businessUnit": "AKBOL",
"type": "1"
},
{
"state": "USED",
"terminalId": "B171",
"ticketNumber": "826079",
"date": {
"$date": "2025-09-18T17:06:36.804Z"
},
"cashierId": "3",
"amount": -437050,
"beforeBalance": 468050,
"invoiceNumber": "ctg752",
"extendedInvoiceNumber": "ctg00000000752",
"transactionId": "3c379a95-3504-4b2c-ba36-394978ec323f",
"observation": "POS",
"businessUnit": "AKBOL",
P á g i n a 36 | 41
"type": "1"
},
{
"state": "USED",
"terminalId": "B171",
"ticketNumber": "826080",
"date": {
"$date": "2025-09-18T18:52:13.804Z"
},
"cashierId": "3",
"amount": -31000,
"beforeBalance": 31000,
"invoiceNumber": "ctg753",
"extendedInvoiceNumber": "ctg00000000753",
"transactionId": "5b91abcd-7732-4a90-b833-54af1117ce9e",
"observation": "POS",
"businessUnit": "AKBOL",
"type": "1"
}
],
"giftCardId": "xJZMiwlDI+h8vDHCGyT3Wd/q+Q21LW4swnEnEhKsvHY=",
"_class": "uy.com.geocom.alkosto.bonoservice.domain.Bono"
}
VOIDED:
{
"_id": "12B17154739D",
"balance": 500000,
"currentBalance": 0,
"retentionAmount": 0,
"beneficiaryId": "1_11111",
"beneficiaryName": "HILDA RUDAS",
"clientId": "11111",
"clientName": "HILDA RUDAS",
"clientDoc": "CEDULA DE CIUDADANIA",
"clientDocType": "C",
"concept": "Giftcard",
"state": "VOIDED",
"digitalSending": false,
"updated": {
"$date": "2025-09-18T19:06:29.087Z"
},
"createDate": {
"$date": "2025-09-18T19:06:29.084Z"
},
"activationDate": {
"$date": "2025-09-18T03:00:00.000Z"
},
"expirationDate": {
"$date": "2026-03-18T02:59:59.000Z"
},
"stateSource": [
{
"state": "ACTIVE",
"terminalId": "B171",
"ticketNumber": "826083",
"date": {
"$date": "2025-09-18T19:06:29.087Z"
},
"cashierId": "3",
"amount": 500000,
"invoiceNumber": "ctg755",
"extendedInvoiceNumber": "ctg00000000755",
"acta": "B1326",
"businessUnit": "AKBOL",
"giftBono": "N"
},
{
"state": "VOIDED",
P á g i n a 37 | 41
"ticketNumber": "826084",
"date": {
"$date": "2025-09-18T19:07:01.533Z"
},
"cashierId": "3",
"authorizerId": "10",
"amount": -500000,
"invoiceNumber": "B171121",
"extendedInvoiceNumber": "0B10071B171121",
"transactionId": "dae0f0dc-b392-4fba-b4f0-69458589f034",
"businessUnit": "AKBOL",
"reasonCode": "58",
"reasonDescription": "X Anulacion"
}
],
"giftCardId": "oX6dsPK9INOrcow52k3dgV2x2EVysa1h/4T/Ab/tlgs=",
"_class": "uy.com.geocom.alkosto.bonoservice.domain.Bono"
}
Colección “giftCards”:
PRINTING:
{
"_id": "b3PBx3HAF8VIm7Sm5LL19625wx6DFnriYTEOkqIGgAA=",
"barCode": "b3PBx3HAF8VIm7Sm5LL19xktO9djxVhehvq6qUGDEXM=",
"state": "PRINTING",
"scratchCode": "FysPAD7IRTXiLJUE07Mmpw==",
"pinInternet": "HHO+AC7cffXoP1eI+Va+2w==",
"createdDate": {
"$date": "2025-08-22T15:02:46.602Z"
},
"updatedDate": {
"$date": "2025-08-22T15:02:46.602Z"
},
"_class": "uy.com.geocom.alkosto.bonoservice.domain.giftcard.GiftCard”
}
ACTIVE:
{
"_id": "DBIL2ZqUk90hdtiZRbmHppYm+TNJzrZ6HolHsdeA/mU=",
"barCode": "DBIL2ZqUk90hdtiZRbmHpstKX2PPtzXBzHH7Rfx+JVU=",
"state": "ACTIVE",
"bonoNumber": "12B171547399",
"scratchCode": "0hq89JCCDzm+xHphLoNLWg==",
"pinInternet": "dBlOhQPliPBZfoegXgJyGw==",
"businessUnit": "AKBOL",
"createdDate": {
"$date": "2025-09-18T12:22:23.143Z"
},
"updatedDate": {
"$date": "2025-09-18T12:41:54.087Z"
},
"activationDate": {
"$date": "2025-09-18T12:41:54.087Z"
},
"_class": "uy.com.geocom.alkosto.bonoservice.domain.giftcard.GiftCard"
}
USED:
{
"_id": "xJZMiwlDI+h8vDHCGyT3Wd/q+Q21LW4swnEnEhKsvHY=",
"barCode": "xJZMiwlDI+h8vDHCGyT3WVTxY4MojnKXce2mCS3VxSQ=",
"state": "USED",
"bonoNumber": "12B171547398",
"scratchCode": "+GYs1pSdT50KnifAalNAcw==",
P á g i n a 38 | 41
"pinInternet": "6y/zgi6Mw5yZDEQ7UOJmwA==",
"businessUnit": "AKBOL",
"createdDate": {
"$date": "2025-09-18T12:22:23.146Z"
},
"updatedDate": {
"$date": "2025-09-18T18:52:13.805Z"
},
"activationDate": {
"$date": "2025-09-18T12:41:54.033Z"
},
"_class": "uy.com.geocom.alkosto.bonoservice.domain.giftcard.GiftCard"
}
Colección “giftCardMassive”:
{
"_id": "11111_98_19082025_31122025_5000_26082025",
"client": "11111",
"localId": "98",
"initDate": {
"$date": "2025-08-19T03:00:00.000Z"
},
"endDate": {
"$date": "2025-12-31T03:00:00.000Z"
},
"barCodeList": [
"ixi18H3gQz0/ELCEcZMzjLqjaNno1+RBFIOiSvKjIc8=",
"XNPMND/BfjTcCAgPeNI18ct+T2xwjV1/tdb0qcm5AkI=",
"4gvaSwKjebp3Blq4fkE3KhktO9djxVhehvq6qUGDEXM=",
…
],
"amount": 5000,
"creationDate": {
"$date": "2025-08-26T19:18:46.623Z"
},
"state": "LOAD",
"_class": "uy.com.geocom.alkosto.bonoservice.domain.giftcard.GiftCardMassive"
}
Estados posibles: LOAD – PROCESSED - ERROR
Servicios web disponibles
Los servicios web que se encuentran expuestos por parte del aplicativo bono-service se puede
encontrar en el swagger de dicho aplicativo a través de la url:
http://{ipmicroservicios}:7004/swagger-ui/index.html
P á g i n a 39 | 41
ANALISIS DE RIESGOS
Riesgo
Descripción
I
m
p
ac
to
Pro
ba
bili
da
d
Mitigación
Resp
onsab
le
Integración
REST/SOAP
Migración de servicios SOAP a
REST puede generar
incompatibilidades o errores en
consumo desde Hybris.
Al
to
Me
dia
Pruebas unitarias y de
integración con Hybris.
Validar contratos de
servicios en Swagger.
Equip
o de
Desar
rollo
Gestión de
estados en
MongoDB
Estados como ACTIVE, USED,
VOIDED deben mantenerse
consistentes. Errores pueden
generar saldos incorrectos.
Al
to
Alt
a
Validaciones
automáticas en
backend. Auditoría de
transacciones.
Equip
o
Backe
nd
Carga masiva
de GiftCards
Procesos masivos pueden fallar
por formato incorrecto o fechas
inválidas.
M
e
di
o
Alt
a
Validación previa del
archivo .csv. Logs
detallados y rollback en
caso de error.
Equip
o
Técni
co
Configuraciones
por
propiedades
Propiedades mal configuradas
pueden habilitar
funcionalidades no deseadas.
Al
to
Me
dia
Checklist de
configuración por
ambiente. Validación en
QA antes de producción.
Equip
o QA
Enmascaramien
to de datos
sensibles
Mal enmascaramiento puede
exponer datos de tarjetas.
Al
to
Me
dia
Pruebas de seguridad y
validación de visibilidad
por rol.
Equip
o de
Segur
idad
Exposición de
PIN o códigos
scratch
Si no se enmascaran
correctamente, pueden ser
usados indebidamente.
Al
to
Alt
a
Encriptación y
enmascaramiento
obligatorio en UI y logs.
Equip
o de
Segur
idad
Acceso no
autorizado a
servicios
Servicios REST pueden ser
accedidos sin token válido.
Al
to
Me
dia
Autenticación y
autorización por token
JWT. Validación en
gateway.
Equip
o
DevO
ps
Manipulación
de estados por
usuarios
Cambios manuales en
MongoDB pueden alterar el
flujo de negocio.
Al
to
Baj
a
Restricción de acceso a
base de datos. Auditoría
y control de cambios.
DBA
Errores en caja
física
Cajeros pueden ingresar mal los
datos o no seguir el flujo
correcto.
M
e
di
o
Alt
a
Capacitación,
validaciones en UI,
mensajes claros de
error.
Equip
o de
Sopor
te
Redención
parcial mal
aplicada
Si no se actualiza
correctamente el saldo, puede
haber inconsistencias.
Al
to
Me
dia
Validación automática
del currentBalance y
logs de transacción.
Equip
o
Backe
nd
Anulación de
ventas con
Si no se valida el estado físico,
puede haber fraude.
Al
to
Me
dia
Validación física
obligatoria antes de
Cajer
o /
P á g i n a 40 | 41
GiftCard
dañada
anulación. Registro
fotográfico opcional.
Super
visor
Fuentes de
datos
inconsistentes
Reportes pueden tomar datos
de bono-report o bono-service
según fecha.
M
e
di
o
Me
dia
Validar propiedad
date.use.bono.service.D
B y sincronizar fuentes.
Equip
o de
Repor
tes
Errores en
conciliación ERP
Exportaciones pueden fallar si
no se respetan formatos o
fechas.
Al
to
Me
dia
Validaciones previas,
pruebas de exportación,
logs detallados.
Equip
o ERP
Campos
faltantes en
reportes
Si no se migran todos los
campos, reportes pueden estar
incompletos.
M
e
di
o
Me
dia
Validación de estructura
completa en
bonoReportItem.
Equip
o de
Repor
tes
Configuración
incorrecta de
propiedades
Activar/desactivar
funcionalidades puede causar
errores operativos.
Al
to
Alt
a
Checklist de
configuración por
ambiente. Validación en
QA antes de producción.
Equip
o QA
Servicios REST
no disponibles
o mal
configurados
Endpoints pueden fallar si no
están correctamente expuestos.
Al
to
Me
dia
Pruebas de conectividad
y validación en Swagger.
Monitoreo de logs en
tiempo real.
Equip
o
DevO
ps
Errores en
conexión con
MongoDB
Si la base de datos no está
correctamente conectada, los
movimientos no se registran.
Al
to
Me
dia
Validación de conexión
previa. Backup y
restauración de datos.
DBA
Carga masiva
de GiftCards
con errores
Archivos .csv mal formateados
o fuera de rango pueden
bloquear el proceso.
M
e
di
o
Alt
a
Validación automática
del archivo antes de
carga. Logs detallados y
rollback.
Equip
o
Técni
co
Problemas de
compatibilidad
entre versiones
de servicios
Diferencias entre versiones de
bono-service, GeoPOS, Hybris,
etc.
Al
to
Me
dia
Validación cruzada de
versiones. Pruebas de
integración previas.
Equip
o de
Desar
rollo
Errores en
impresión de
vouchers o
actas
Si no se configuran
correctamente las rutas o
formatos, no se generan los
documentos.
M
e
di
o
Me
dia
Validación de rutas
(pdf.report.path) y
pruebas de impresión.
Equip
o
Técni
co
Falta de
sincronización
entre módulos
GeoConciliación, ERP, POS
pueden tener desfases en
datos.
Al
to
Me
dia
Validación de propiedad
date.use.bono.service.D
B y pruebas de
conciliación.
Equip
o de
Integr
ación
Problemas de
seguridad en
activación
PINs o códigos scratch visibles o
mal encriptados.
Al
to
Alt
a
Enmascaramiento
obligatorio. Validación
de visibilidad por rol.
Equip
o de
Segur
idad
Errores en
redención en
caja
Si el medio de pago no está
correctamente configurado, se
bloquea la operación.
Al
to
Me
dia
Validación de
sale.bono.enabled y
sale.giftcard.enabled.
Pruebas en caja física.
Equip
o QA
Falta de
capacitación al
personal
Cajeros o técnicos pueden
cometer errores por
desconocimiento.
M
e
Alt
a
Capacitación previa.
Manuales operativos y
simulaciones.
Equip
o de
P á g i n a 41 | 41
di
o
Form
ación
